IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/p_man/cat3/SCSL/zheevr.z/zheevr

Text File | 2002-10-03 | 12.1 KB | 331 lines

ZZZZHHHHEEEEEEEEVVVVRRRR((((3333SSSS))))                                                          ZZZZHHHHEEEEEEEEVVVVRRRR((((3333SSSS))))



NNNNAAAAMMMMEEEE
     ZHEEVR - compute selected eigenvalues and, optionally, eigenvectors of a
     complex Hermitian matrix T

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     SUBROUTINE ZHEEVR( JOBZ, RANGE, UPLO, N, A, LDA, VL, VU, IL, IU, ABSTOL,
                        M, W, Z, LDZ, ISUPPZ, WORK, LWORK, RWORK, LRWORK,
                        IWORK, LIWORK, INFO )

         CHARACTER      JOBZ, RANGE, UPLO

         INTEGER        IL, INFO, IU, LDA, LDZ, LIWORK, LRWORK, LWORK, M, N

         DOUBLE         PRECISION ABSTOL, VL, VU

         INTEGER        ISUPPZ( * ), IWORK( * )

         DOUBLE         PRECISION RWORK( * ), W( * )

         COMPLEX*16     A( LDA, * ), WORK( * ), Z( LDZ, * )

IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
     These routines are part of the SCSL Scientific Library and can be loaded
     using either the -lscs or the -lscs_mp option.  The -lscs_mp option
     directs the linker to use the multi-processor version of the library.

     When linking to SCSL with -lscs or -lscs_mp, the default integer size is
     4 bytes (32 bits). Another version of SCSL is available in which integers
     are 8 bytes (64 bits).  This version allows the user access to larger
     memory sizes and helps when porting legacy Cray codes.  It can be loaded
     by using the -lscs_i8 option or the -lscs_i8_mp option. A program may use
     only one of the two versions; 4-byte integer and 8-byte integer library
     calls cannot be mixed.

PPPPUUUURRRRPPPPOOOOSSSSEEEE
     ZHEEVR computes selected eigenvalues and, optionally, eigenvectors of a
     complex Hermitian matrix T. Eigenvalues and eigenvectors can be selected
     by specifying either a range of values or a range of indices for the
     desired eigenvalues.

     Whenever possible, ZHEEVR calls ZSTEGR to compute the
     eigenspectrum using Relatively Robust Representations.  ZSTEGR computes
     eigenvalues by the dqds algorithm, while orthogonal eigenvectors are
     computed from various "good" L D L^T representations (also known as
     Relatively Robust Representations). Gram-Schmidt orthogonalization is
     avoided as far as possible. More specifically, the various steps of the
     algorithm are as follows. For the i-th unreduced block of T,
        (a) Compute T - sigma_i = L_i D_i L_i^T, such that L_i D_i L_i^T
             is a relatively robust representation,
        (b) Compute the eigenvalues, lambda_j, of L_i D_i L_i^T to high
            relative accuracy by the dqds algorithm,
        (c) If there is a cluster of close eigenvalues, "choose" sigma_i



                                                                        PPPPaaaaggggeeee 1111






ZZZZHHHHEEEEEEEEVVVVRRRR((((3333SSSS))))                                                          ZZZZHHHHEEEEEEEEVVVVRRRR((((3333SSSS))))



            close to the cluster, and go to step (a),
        (d) Given the approximate eigenvalue lambda_j of L_i D_i L_i^T,
            compute the corresponding eigenvector by forming a
            rank-revealing twisted factorization.
     The desired accuracy of the output can be specified by the input
     parameter ABSTOL.

     For more details, see "A new O(n^2) algorithm for the symmetric
     tridiagonal eigenvalue/eigenvector problem", by Inderjit Dhillon,
     Computer Science Division Technical Report No. UCB//CSD-97-971, UC
     Berkeley, May 1997.


     Note 1 : ZHEEVR calls ZSTEGR when the full spectrum is requested on
     machines which conform to the ieee-754 floating point standard.  ZHEEVR
     calls DSTEBZ and ZSTEIN on non-ieee machines and
     when partial spectrum requests are made.

     Normal execution of ZSTEGR may create NaNs and infinities and hence may
     abort due to a floating point exception in environments which do not
     handle NaNs and infinities in the ieee standard default manner.


AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
     JOBZ    (input) CHARACTER*1
             = 'N':  Compute eigenvalues only;
             = 'V':  Compute eigenvalues and eigenvectors.

     RANGE   (input) CHARACTER*1
             = 'A': all eigenvalues will be found.
             = 'V': all eigenvalues in the half-open interval (VL,VU] will be
             found.  = 'I': the IL-th through IU-th eigenvalues will be found.

     UPLO    (input) CHARACTER*1
             = 'U':  Upper triangle of A is stored;
             = 'L':  Lower triangle of A is stored.

     N       (input) INTEGER
             The order of the matrix A.  N >= 0.

     A       (input/output) COMPLEX*16 array, dimension (LDA, N)
             On entry, the Hermitian matrix A.  If UPLO = 'U', the leading N-
             by-N upper triangular part of A contains the upper triangular
             part of the matrix A.  If UPLO = 'L', the leading N-by-N lower
             triangular part of A contains the lower triangular part of the
             matrix A.  On exit, the lower triangle (if UPLO='L') or the upper
             triangle (if UPLO='U') of A, including the diagonal, is
             destroyed.

     LDA     (input) INTEGER
             The leading dimension of the array A.  LDA >= max(1,N).




                                                                        PPPPaaaaggggeeee 2222






ZZZZHHHHEEEEEEEEVVVVRRRR((((3333SSSS))))                                                          ZZZZHHHHEEEEEEEEVVVVRRRR((((3333SSSS))))



     VL      (input) DOUBLE PRECISION
             VU      (input) DOUBLE PRECISION If RANGE='V', the lower and
             upper bounds of the interval to be searched for eigenvalues. VL <
             VU.  Not referenced if RANGE = 'A' or 'I'.

     IL      (input) INTEGER
             IU      (input) INTEGER If RANGE='I', the indices (in ascending
             order) of the smallest and largest eigenvalues to be returned.  1
             <= IL <= IU <= N, if N > 0; IL = 1 and IU = 0 if N = 0.  Not
             referenced if RANGE = 'A' or 'V'.

     ABSTOL  (input) DOUBLE PRECISION
             The absolute error tolerance for the eigenvalues.  An approximate
             eigenvalue is accepted as converged when it is determined to lie
             in an interval [a,b] of width less than or equal to

             ABSTOL + EPS *   max( |a|,|b| ) ,

             where EPS is the machine precision.  If ABSTOL is less than or
             equal to zero, then  EPS*|T|  will be used in its place, where
             |T| is the 1-norm of the tridiagonal matrix obtained by reducing
             A to tridiagonal form.

             See "Computing Small Singular Values of Bidiagonal Matrices with
             Guaranteed High Relative Accuracy," by Demmel and Kahan, LAPACK
             Working Note #3.

             If high relative accuracy is important, set ABSTOL to DLAMCH(
             'Safe minimum' ).  Doing so will guarantee that eigenvalues are
             computed to high relative accuracy when possible in future
             releases.  The current code does not make any guarantees about
             high relative accuracy, but furutre releases will. See J. Barlow
             and J. Demmel, "Computing Accurate Eigensystems of Scaled
             Diagonally Dominant Matrices", LAPACK Working Note #7, for a
             discussion of which matrices define their eigenvalues to high
             relative accuracy.

     M       (output) INTEGER
             The total number of eigenvalues found.  0 <= M <= N.  If RANGE =
             'A', M = N, and if RANGE = 'I', M = IU-IL+1.

     W       (output) DOUBLE PRECISION array, dimension (N)
             The first M elements contain the selected eigenvalues in
             ascending order.

     Z       (output) COMPLEX*16 array, dimension (LDZ, max(1,M))
             If JOBZ = 'V', then if INFO = 0, the first M columns of Z contain
             the orthonormal eigenvectors of the matrix A corresponding to the
             selected eigenvalues, with the i-th column of Z holding the
             eigenvector associated with W(i).  If JOBZ = 'N', then Z is not
             referenced.  Note: the user must ensure that at least max(1,M)
             columns are supplied in the array Z; if RANGE = 'V', the exact



                                                                        PPPPaaaaggggeeee 3333






ZZZZHHHHEEEEEEEEVVVVRRRR((((3333SSSS))))                                                          ZZZZHHHHEEEEEEEEVVVVRRRR((((3333SSSS))))



             value of M is not known in advance and an upper bound must be
             used.

     LDZ     (input) INTEGER
             The leading dimension of the array Z.  LDZ >= 1, and if JOBZ =
             'V', LDZ >= max(1,N).

     ISUPPZ  (output) INTEGER ARRAY, dimension ( 2*max(1,M) )
             The support of the eigenvectors in Z, i.e., the indices
             indicating the nonzero elements in Z. The i-th eigenvector is
             nonzero only in elements ISUPPZ( 2*i-1 ) through ISUPPZ( 2*i ).

     WORK    (workspace/output) COMPLEX*16 array, dimension (LWORK)
             On exit, if INFO = 0, WORK(1) returns the optimal LWORK.

     LWORK   (input) INTEGER
             The length of the array WORK.  LWORK >= max(1,2*N).  For optimal
             efficiency, LWORK >= (NB+1)*N, where NB is the max of the
             blocksize for ZHETRD and for ZUNMTR as returned by ILAENV.

             If LWORK = -1, then a workspace query is assumed; the routine
             only calculates the optimal size of the WORK array, returns this
             value as the first entry of the WORK array, and no error message
             related to LWORK is issued by XERBLA.

     RWORK   (workspace/output) DOUBLE PRECISION array, dimension (LRWORK)
             On exit, if INFO = 0, RWORK(1) returns the optimal (and minimal)
             LRWORK.

     LRWORK   (input) INTEGER
             The length of the array RWORK.  LRWORK >= max(1,24*N).

             If LRWORK = -1, then a workspace query is assumed; the routine
             only calculates the optimal size of the RWORK array, returns this
             value as the first entry of the RWORK array, and no error message
             related to LRWORK is issued by XERBLA.

     IWORK   (workspace/output) INTEGER array, dimension (LIWORK)
             On exit, if INFO = 0, IWORK(1) returns the optimal (and minimal)
             LIWORK.

     LIWORK   (input) INTEGER
             The dimension of the array IWORK.  LIWORK >= max(1,10*N).

             If LIWORK = -1, then a workspace query is assumed; the routine
             only calculates the optimal size of the IWORK array, returns this
             value as the first entry of the IWORK array, and no error message
             related to LIWORK is issued by XERBLA.

     INFO    (output) INTEGER
             = 0:  successful exit
             < 0:  if INFO = -i, the i-th argument had an illegal value



                                                                        PPPPaaaaggggeeee 4444






ZZZZHHHHEEEEEEEEVVVVRRRR((((3333SSSS))))                                                          ZZZZHHHHEEEEEEEEVVVVRRRR((((3333SSSS))))



             > 0:  Internal error

FFFFUUUURRRRTTTTHHHHEEEERRRR DDDDEEEETTTTAAAAIIIILLLLSSSS
     Based on contributions by
        Inderjit Dhillon, IBM Almaden, USA
        Osni Marques, LBNL/NERSC, USA
        Ken Stanley, Computer Science Division, University of
          California at Berkeley, USA


SSSSEEEEEEEE AAAALLLLSSSSOOOO
     INTRO_LAPACK(3S), INTRO_SCSL(3S)

     This man page is available only online.









































                                                                        PPPPaaaaggggeeee 5555